OpenAPI specification requirements
Before you import an OpenAPI specification, whether by uploading a file or importing from a URI, review the requirements on this page. Cloud API Management validates your specification against these rules, and the import fails if they are not met.
Supported versions and formats
Cloud API Management supports:
- OpenAPI 2.0
- OpenAPI 3.0.x (for example, 3.0.0, 3.0.1, 3.0.3)
Both JSON and YAML file formats are accepted.
OpenAPI 3.1.x is not supported. If your specification declares openapi: 3.1.x, the import fails.
OpenAPI Spec required fields
Required fields differ depending on the specification version.
OpenAPI 2.0
The following table lists the required fields for an OpenAPI 2.0 specification.
| Level | Required fields |
|---|---|
| Root | swagger (must equal "2.0"), info, paths |
info | title, version |
license (if present) | name |
| Each operation | responses |
| Path parameter | required: true |
| Non-body parameter | name, in, type |
| Body parameter | name, in, schema |
host | Not required by the schema, but required at runtime. Import fails without it. |
OpenAPI 3.0.x
The following table lists the required fields for an OpenAPI 3.0.x specification.
| Level | Required fields |
|---|---|
| Root | openapi, info, paths |
info | title, version |
license (if present) | name |
servers[*] (if present) | url |
| Each operation | responses |
| Path parameter | name, in, schema or content, required: true |
requestBody (if present) | content |
OpenAPI 3.0.x specifications have no additional runtime checks beyond the fields listed above, unlike OpenAPI 2.0's host validation.
Custom (x-) extension fields
Cloud API Management does not support custom x- vendor extension fields for controlling import or endpoint behavior. You can include x- prefixed fields in your specification for your own documentation purposes, but Cloud API Management ignores them during import — they have no effect on the API definition, endpoints, domain, or organization settings that are created.
